2025 iThome 鐵人賽
「 Flutter ：30 天打造念佛 App ，跨平台從 Mobile 到 VR ，讓極樂世界在眼前實現 ! 」
番外篇
「 Flutter Meta Horizon Store 上架 實戰應用篇 — 2D Android App 送審流程 」

前言

前幾天我們已經將 念佛 App 進行 Meta Quest 3 實機測試，
今天我們會先從 Meta 官方文件了解「 2D Android App 上架規範 」 ，
接著依據規範進行「 專案檢查與前置準備 」 ，
最後在 Meta 開發人員面板完成 「 Meta Horizon Store 送審流程 」!

文章目錄
一、上架規範
二、前置準備
三、送審流程

一、上架規範

1. Meta 官方文件

2. Android 設計要求

(1) Navigation 導覽

(2) Inputs and hit targets 輸入與觸控目標

(3) Color 色彩

(4) Typography 字體排版

(5) Icons 圖示

3. VRC 檢查 ( Virtual Reality Check )

(1) 打包要求

打包要求的實作，我們會在下一章節「 前置準備 」進行。

(2) 功能要求

(3) 安全要求

(4) 輸入要求

(5) 素材要求

(6) 廣告要求

(7) 隱私政策要求

(8) 內容要求

(9) 發布要求

二、前置準備

1. 發行版應用程式資訊清單要求

(1) android/app/build.gradle.kts

Meta 官方文件：Android minSdk: 29-32 ；Android targetSdk = 32
Google Play 官方文件：Android targetSdk = 35
因為 Meta 和 Google 兩方要求的 targetSdk 不同，所以我們必須準備不同的變體。
備註：變體（build variant）= buildType × productFlavor 的笛卡兒積

如果之前沒有使用 flavorizr 設定 flavors
android/app/build.gradle.kts 新增 productFlavors { create("prodMeta") }

//結果示例，android/app/build.gradle.kts
android {
 
  flavorDimensions("app")
  
  productFlavors {
    create("prodMeta") {
      dimension = "app"
      applicationId = "你的 applicationId "
      targetSdk = 32          // ← Meta Horizon Store
      resValue("string", "app_name", "你的 app 名稱")
    }
    create("prod") {
      dimension = "app"
      applicationId = "你的 applicationId"
      targetSdk = 35       // ← Google Play Store
      resValue("string", "app_name", "你的 app 名稱")
    }
  }
}

如果之前有用 flavorizr 設定 flavors，
android/app/flavorizr.gradle.kts 新增 productFlavors "prodMeta"

//結果示例，android/app/flavorizr.gradle.kts

import com.android.build.gradle.AppExtension

val android = project.extensions.getByType(AppExtension::class.java)

android.apply {
    flavorDimensions("app")

    productFlavors {
        create("dev") {
            dimension = "app"
            applicationId = "com.earth.amitabha.dev"
            resValue(type = "string", name = "app_name", value = "念佛 Dev")
        }
        create("staging") {
            dimension = "app"
            applicationId = "com.earth.amitabha.staging"
            resValue(type = "string", name = "app_name", value = "念佛 Staging")
        }
        create("prod") {
            dimension = "app"
            applicationId = "com.earth.amitabha"
            resValue(type = "string", name = "app_name", value = "念佛")
        }
        create("prodMeta") {
            dimension = "app"
            applicationId = "com.earth.amitabha"
            targetSdk = 32
            resValue(type = "string", name = "app_name", value = "念佛")          
        }   
    }
}

(可選)
android/app/build.gradle.kts 同樣寫上 productFlavors { create("prodMeta") } ，
避免跑 flavorizr 覆蓋 prodMeta 段落直接消失。

//結果示例，android/app/build.gradle.kts

android {
    defaultConfig {
    ...
    }
    
    signingConfigs {
    ...   
    }

    buildTypes {
    ...  
    }
}


apply { from("flavorizr.gradle.kts") }

// 追加在 apply { from("flavorizr.gradle.kts") } 下面

android {
  productFlavors {
    maybeCreate("prodMeta").apply {
      dimension = "app"
      applicationId = "com.earth.amitabha"
      targetSdk = 32
      resValue(type = "string", name = "app_name", value = "念佛")
    }
  }
}

(2) android/app/src/prodMeta/AndroidManifest.xml

Meta 要求的重點宣告，有兩項需要注意：

• 宣告 頭部追蹤 (uses-feature):
  Play 商店會進行裝置相容性過濾；
  不具備頭部追蹤功能的裝置，可能看不到也無法安裝 App。
• 宣告 從最近使用清單排除 (activity):
  從最近使用清單排除，對於 Mobile 用戶較不友善。

所以我們將上架 Meta 的相關宣告另外寫 prodMeta/AndroidManifest.xml，
上架 Play 商店則維持使用 main/AndroidManifest.xml ， Mobile 端使用者不受影響。

//僅列差異鍵
//Gradle 會合併 main/AndroidManifest.xml、prodMeta/AndroidManifest.xml

<!-- installLocation 代表 app 安裝位置，寫在最外層 manifest 屬性 -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    android:installLocation="auto"> 
    
<!-- 權限需求，寫在 manifest 子節點 -->
		<uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <uses-permission android:name="android.permission.INTERNET" />
    
<!-- 頭部追蹤，寫在 manifest 子節點  -->
    <uses-feature
        android:name="android.hardware.vr.headtracking" 
        android:required="true"
        android:version="1" />
        
    <!-- 支援的 Quest 裝置，寫在 application 子節點-->  
    <application android:label="@string/app_name" ...>
        <meta-data 
            android:name="com.oculus.supportedDevices"
            android:value="quest2|quest3|quest3s" /> 
            
				<!-- excludeFromRecents 代表從近期使用清單排除， 寫在 Activity 子節點-->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:excludeFromRecents="true" 
            ...>
        </activity>
    </application>
</manifest>

• AndroidManifest .xml 自動合併
  打包時 Android Gradle Plugin 會自動將不同的 AndroidManifest.xml 進行合併。
• 合併優先順序 (由最低合併至最高)：
  library manifest(最低優先順序) ⭢ main manifest ⭢ build variant manifest(最高優先順序)
• 備註：
  最外層的 manifest 屬性不會被合併，系統只會使用優先順序最高的 AndroidManifest.xml 最外層 manifest 屬性。

2. 檢查權限功能與相依套件

備註：
Android Studio IDE 可以使用 Meta Horizon Android Studio 插件 偵測不支援的相依套件與權限

(1) Meta 禁止的權限(摘要)：

(2) Meta 需審核的權限(摘要)：

備註：
HEADSET_CAMERA ：
Meta Quest 取得空間真實環境畫面，須透過頭顯的外部相機(HEADSET_CAMERA 權限)
AVATAR_CAMERA ：
在會議或通話中輸出 AVATAR 虛擬分身影像作為視訊來源（AVATAR_CAMERA 權限）

(3) Meta 不支援的相依套件：

常見的 Google 驗證、登入 、定位等 GMS 都不支援
Android Notifications 要改用 Meta User Notifications

• 不支援的 Android 相依套件

• 不支援的 Google Mobile Services（GMS） 相依套件

• 不支援的 Firebase 相依套件

Quest 裝置支援所有不需要 GMS 的 Firebase 相依套件。

3. 簽章

備註：
Android APK 簽章方案
v1 方案：基於 JAR 簽章，不保護部分 APK 內容(例如 ZIP 數據)
v2 方案：APK 簽章方案 v2 ，Android 7.0 引入，全檔案簽署配置、強化保護 APK 內容。
v3 方案：APK 簽章方案 v3， Android 9.0 引入，支援金鑰輪替。

(1) 建立金鑰與金鑰儲存庫 keystore

//終端機指令

//建立本機 home 目錄資料夾，～展開會是 /Users/<使用者名稱>
mkdir -p ~/.keystores

//建立金鑰寫進keystore
keytool -genkeypair -v -keystore ~/.keystores/release.jks \
  -storetype JKS -alias release -keyalg RSA -keysize 2048 -validity 10000
  
//鎖權限：僅擁有者能讀寫
chmod 600 ~/.keystores/release.jks

//憑證資訊

輸入金鑰儲存庫密碼:  
重新輸入新密碼: 
Enter the distinguished name. Provide a single dot (.) to leave a sub-component empty or press ENTER to use the default value in braces.
您的名字與姓氏為何？
  [Unknown]:  
您的組織單位名稱為何？
  [Unknown]:  
您的組織名稱為何？
  [Unknown]:  
您所在的城市或地區名稱為何？
  [Unknown]:  
您所在的州及省份名稱為何？
  [Unknown]:  
此單位的兩個字母國別代碼為何？
  [Unknown]:  

(2) 建立 gradle.properties

Gradle 是 Android 的建構系統，用途是將原始碼轉換為可執行的應用程式，
gradle.properties 是使用者設定檔，讓 Gradle 打包簽章時可以找到金鑰，也避免金鑰放進版控。

//終端機指令

//建立在本機 home 目錄
nano ~/.gradle/gradle.properties

• 如果已經在打包 play 商店 aab 時建立 gradle.properties，使用同一份即可。
• KEY_ALIAS 是 金鑰別名，用於指定 KEYSTORE 特定一把金鑰。
• 商店上架核對的是簽章憑證指紋 X.509 ( 常用 SHA-256 )，
  所以 KEY_ALIAS 如何命名不會影響，只要記得保持使用同一把金鑰。

#空白 gradle.properties 設定資訊

MY_KEYSTORE=/Users/<使用者名稱>/.keystores/release.jks
MY_KEY_ALIAS=release 
MY_KEYSTORE_PASSWORD=<你的密碼>
MY_KEY_PASSWORD=<你的密碼>

//儲存離開 gradle.properties
存檔方式：Ctrl + O (英文字母O) → Enter
離開方式：Ctrl + X

(3) 綁定簽章 android/app/build.gradle.kts 添加 signingConfigs、buildTypes

// android/app/build.gradle.kts 添加以下內容

signingConfigs {
        create("release") {
            val ks = (project.findProperty("MY_KEYSTORE") ?: System.getenv("MY_KEYSTORE")) as String
            storeFile = file(ks)
            storePassword = (project.findProperty("MY_KEYSTORE_PASSWORD")
                ?: System.getenv("MY_KEYSTORE_PASSWORD")) as String
            keyAlias = (project.findProperty("MY_KEY_ALIAS")
                ?: System.getenv("MY_KEY_ALIAS")) as String
            keyPassword = (project.findProperty("MY_KEY_PASSWORD")
                ?: System.getenv("MY_KEY_PASSWORD")) as String
        }
}

buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
             isMinifyEnabled = false
             isShrinkResources = false
        }
}

4. 打包 APK

APK：可直接安裝到裝置的安裝檔
AAB：商店用的發佈檔，商店會依使用者裝置產出並簽名最佳化的 APK。

//終端機指令：打包 APK
flutter build apk --release --flavor prodMeta --target-platform=android-arm64

//通常輸出路徑：
build/app/outputs/flutter-apk/app-prodmeta-release.apk

5. 驗證簽章

//終端機指令

//確認 apksigner 所在路徑
ls ~/Library/Android/sdk/build-tools/*/apksigner

//結果示例
/Users/***/Library/Android/sdk/build-tools/36.0.0/apksigner

//終端機指令

//驗證簽章

 ~/Library/Android/sdk/build-tools/36.0.0/apksigner \
  verify --verbose --print-certs build/app/outputs/flutter-apk/app-prodmeta-release.apk

6. 檢查檔案大小

ls -lh build/app/outputs/flutter-apk/app-prodmeta-release.apk

//結果示例，101MiB(106.2 MB)
101M Oct 26 19:48 build/app/outputs/flutter-apk/app-prodmeta-release.apk

7. Meta Quest 3 實機測試 apk

adb -s <IP>:5555 install -r build/app/outputs/flutter-apk/app-prodmeta-release.apk

三、送審流程

1. 建立應用程式 Meta Horizon 開發者面板

2. 驗證組織

3. 簽署開發商發布協議

4. 提供個人角色與目標

5. 自我驗證應用程式年齡層

6. 配置分享設定

7. 添加隱私政策

8. Meta Quest Developer Hub 上傳 APK

Meta Quest Developer Hub for Mac
Meta Quest Developer Hub for Windows

(1) 發布管道 Release Channel

(2) 新增用戶至發布管道

9. 建置版本

10. 設定價格

(1) 上架類型 Listing Type

(2) 開發人員收款設定

在 Meta Horizon Store 販售付費 App/內購，團隊需建立單一財務帳戶，
完成公司/個人資訊、稅籍、法定負責人資料與收款銀行設定。
交易發生後，Meta 會依使用者所在地計算並代收銷售稅，並在每月撥款週期匯款(USD)；
同時扣除平台分潤 30%（除非另有書面約定）。

11. 設定商店資訊與素材

(1) App 資訊

(2) App 類型

(3) App 規格

(4) App 素材：參閱官方 素材設計 指南

(5) App 內容分級

12. 提交送審

13. 審核通過

備註：
如果遇到上架、技術等問題，可以提交支援申請與官方開發者支援團隊聯繫。

• Meta Horizon 開發者支援
  https://developers.meta.com/horizon/support/
• Meta Horizon 開發者論壇
  https://communityforums.atmeta.com/category/horizon-developer-forum
• Meta Horizon 提交支援申請
  https://metahorizondevelopers.atmeta.com/s/

重點回顧